How to play (the long version, including shortcuts)
Making your own levels
Playing on more than one computer
Common problems
History, levels, and other implementations
Hints and strategies
Distribution, Legal Stuff, and reaching me
Comments, suggestions, even (gasp!) bugs
About the author
System requirements
Version history
In Sokoban, you are a warehouse keeper trying to get boxes through a maze of a warehouse to their proper locations. The boxes are so heavy that you can only push one of them at a time. Be careful that you don’t get a box trapped in a corner: the boxes have no handles so they can’t be pulled at all. If you prefer a more glamorous description, replace “box” by “treasure chest”; in fact, I think I’ll do that in the rest of these docs.
There are over 200 different levels included (separated into several collections), and you can make your own levels, too. If you design good levels, I’ll include them in the next version and give you credit.
How to play (the short version)
Run Sokoban, enter your name as the new player, move using the mouse or arrow keys or numeric keypad, and push all of the round treasures into the outlined squares.
Summary of Controls
Keyboard: numeric keypad (8 keys), arrow keys, or your own key choices. Add control or shift to move farther, option to zip to a square.
Mouse: click to move or drag a chest (the program will move you to the place you clicked or push the piece you dragged, if possible). Command-click to drag a piece next to you.
Undo/Redo: Cmd-Z, ESC, F1, or ` to undo; space or Cmd-Y to redo; option-undo to undo a single step. They will auto-repeat if you hold the keys down.
Upgrading from previous versions
Throw away the old version of Sokoban and start playing this version. Be sure to keep the Sokoban Scores file or you’ll have to start over at the beginning! If you’re upgrading from version 1.2, the old levels 51-85 are now part of the “Extra” collection; don’t worry, the game will still know if you completed them (with 3 exceptions: the incredibly easy levels 51, 52, and 53 were replaced by new harder levels, so the game marks them as being uncompleted).
How to play (the long version, including shortcuts)
The first time you run Sokoban, it will prompt you to enter a new player’s name. If it doesn’t, either select your name from the Players menu to pick up where you left off, or select New Player… from the Players menu and make an entry for yourself. Sokoban keeps track of which levels you have solved in the “Sokoban Scores” file; this is normally in the same folder as Sokoban, but may also be placed in your Preferences folder inside the System Folder. If you quit in the middle of a level, then the next time you play Sokoban will load the level you were working on and show you what moves you made. To speed up the process, hold down the shift key.
The first level looks like this, except it’s in color on color monitors:
The treasures are the solid round things lying all over the place. Your job is to push them to the outlined squares using the pusher, which is the round ball with the arrows. There are many ways to move. The most intuitive may be to use the arrow keys to move up, down, left, or right. Shift-arrow key will move you as far as possible in that direction, including pushing treasures. Control-arrow key (if you have a control key) will move you as far as possible without pushing.
Instead of using the arrow keys, you can also use the numeric keypad 2, 4, 6, 8 or w, a, s, and d. Choosing “Set Keys…” from the Edit menu lets you change w, a, s, and d to whatever other keys you want (the numeric keypad and arrow keys can’t be changed). Of course, shift and control work with all the different key sets.
You can also use the mouse to move. The cursor indicates which way you’ll move if you press the button (and you can drag yourself around, too). If you see a cross hair cursor, then clicking will move you to where you clicked by the shortest possible route. Or if you’d rather use the keyboard to move long distances, hold down the option key then move the marquee around (with your favorite movement keys). When you let go of the option key, the player will zip to the square you selected if there’s a clear path.
If you want to zip to a square diagonally next to you, there is a shortcut. Instead of clicking there or pressing <option> left-up, pressing one of the diagonally located keys on the keypad (7, 9, 1, or 3) will do the same thing. You can also use the q, e, z, or x keys if you’re left handed (unless you changed them with the “Set Keys…” command).
The snazziest movement option (and my favorite) is drag-and-drop movement. You can grab a chest with the mouse and drag to it a destination square. If there’s a simple way to push the chest there (without pushing any other chests), it will be moved to the destination. This can be a real time saver on complex levels when you don’t want to maneuver several chests over the same long path by hand. Normally if you click on a square adjacent to you, you’ll move in that direction. If you want to pick up and drag the chest there, just hold down the command key when you click (you’ll see a hand cursor indicating that you can pick up the chest and drag it). You may want to disable the drag-and-drop movement if you set up Sokoban for young children because it can make the children’s levels much too easy; press command-shift-H to disable or enable using the hand to pick up chests. It’s enabled by default.
There are also several menu items that will help you. From the Level menu, you can restart the level if you get stuck. You can also make a temporary save before you mess up, and revert to it when you get stuck later. Or if you’re really stuck, you can move on and try another level, then come back later and work on the unsolved levels.
From the Edit menu, you can undo (and then redo) up to 10 000 of your last moves. There are many shortcuts for undoing: press function key F1 (labeled “undo” on some keyboards), or the ESC or ` key (in the upper left corner of your keyboard). The space bar, shift-F1, shift-ESC, and shift-` are all shortcuts for redo. Sometimes you may only want to undo part of a move (suppose you dragged a chest one square too far). Option-undo will undo one single step of a move (you can also use the option-key with redo, and it works with both the keyboard equivalents and the menu commands themselves).
You can copy or paste in a sequence of moves to a level. Create text using the characters U, D, L, and R (for Up, Down, Left, and Right) from a word processor, paste it into Sokoban, then use Redo to look at the moves. Case doesn’t matter, and other characters are ignored, so you may paste something like “d, r, D, d, L” and the commas and spaces will be ignored. Or you can copy your move history and paste it into your favorite word processor to show your friends.
When someone first completes a level, his solution is saved in the Sokoban Scores file. When you play a level again, the previous best score will be shown, and if you beat it, your solution will replace the old one. To look at your old solution, choose the Load Best Score command in the Level menu and replay the solution by hitting Redo (the easiest way is to hold down the space bar). Sometimes you’ll notice two best scores for a level. That’s because there are really two scores for a level: number of moves used and number of pushes used. Usually, the solution with the fewest moves also has the fewest pushes, but not always. For example, one solution might use 347 moves and 97 pushes, while another uses only 331 moves but 104 pushes.
For information on other menu commands, turn on balloon help while you’re playing Sokoban.
Making your own levels
If you want to make your own levels, it’s easy. Just create a text file in your favorite word processor (SimpleText works well and is included with your system software) and use the ‘Play Screen From File…’ command in the File menu to try it out, or just drop the text file on Sokoban’s icon. If you are running System 7.5 or higher (or another system that supports the Drag Manager), you can select the text in your word processor and drag it to Sokoban’s window to play the level. To copy a level that appears in Sokoban’s window, drag it to your word processor or to the Finder to create a text clipping. To copy an entire collection from Sokoban (even one of the built-in collections), hold down the shift key when you start dragging. You’ll see the window title bar changing as Sokoban converts the levels so you can drag them.
The included Sokoban font can be helpful for designing your own levels because you can see what the level will look like directly in your word processor: type the level in the Sokoban font instead of using Monaco. Just remember that you may have to save the file as text only to use it. For more information about the Sokoban font, see the file “Sokoban font doc”.
This is what a file for level 1 of the Original Levels looks like (using Monaco), along with an explanation of the symbols to use.
#####
# #
#$ #
### $##
# $ $ #
### # ## # ######
# # ## ##### ..#
# $ $ ..#
##### ### #@## ..#
# #########
#######
Symbols used in the screen files:
“ ” (space)—An empty space (floor)
“#”—Walls (the walls will be curved and shadowed automatically)
“.”—Target or goal square
“$”—Treasure
“*”—Treasure on a goal area
“@”—You (the player)
“+”—You standing on a goal square.
There is a limit of 31 columns and 18 rows; additional rows and columns will be ignored. If you make interesting screens, send them to me and I’ll credit you and include them in the next release of the program.
If you want to put more than one level in a file, that’s OK. Look at the “Make your own levels” file included with Sokoban for instructions and examples.
For that extra finishing touch, use ResEdit or another utility program to change the creator of your level file to “SSok” (be sure you have the capitalization correct). Then the file will get a nice icon and can be played by double-clicking on it.
Sokoban can also open levels used by the other two Macintosh sokoban implementations, MacSokoban (by Ingemar Ragnemalm) and JSokoban (by Jason Townsend).
Playing on more than one computer
If you want to play Sokoban on more than one computer (for example, if you have to go to a computer lab to play and never use the same computer twice), just keep the “Sokoban Scores” file in the same folder as Sokoban. It will find it there and record which levels you have completed in that file. You can also start playing by double-clicking on the score file you wish to use.
Common problems
Sometimes if your computer crashes while Sokoban is in the background, the score file gets corrupted. (Sokoban itself is very stable; the only time I have seen it crash is when I set the memory partition below the minimum size). I added code in version 2.3 that should make such corruption very rare if it still occurs at all (for you programmers, I call FlushVol after writing to the disk). If you get the error message “The ‘Sokoban Scores’ file can’t be opened. See the documentation for possible solutions,” try moving the “Sokoban Scores” file out of the Sokoban folder. When you next run Sokoban, it will create a fresh new score file; this new file should work fine, but will not contain a record of the levels you have completed. If you’re handy with ResEdit, copy the ‘USER’ resources from the old Sokoban Scores file into the new one to restore the memory of the completed levels.
When making your own levels, be sure to use the correct symbols and especially to save the file as text only (this is done automatically if you use SimpleText to write your levels).
History, levels, and other implementations
Sokoban was invented in Japan and first released around 1982 or 1984 by Thinking Rabbit. “Sokoban” is Japanese for “warehouse keeper” and the object was to push corrugated cardboard boxes around. In 1984, Spectrum Holobyte produced an English version for IBM-PC computers; the “Original Levels” collection contains the levels from this version.
Two major sokoban versions were released in Japan only: “sokoban perfect” (Thinking Rabbit 1989) with 306 levels, and “sokoban revenge” (Thinking Rabbit 1991) with another 306 levels. Some of these levels appear in the “IQ Carrier” and “Boxxle” collections, but the rest are still available only in Japan. In fact, these two versions are still being sold commercially in Japan by Powerhouse <http://www.powerhouse.co.jp>. I hope to make these levels available in Macintosh format some day, but must first get permission to distribute them.
Not long after the Spectrum Holobyte version appeared, someone wrote versions of Sokoban for MS-DOS and Unix machines. The version I first played only had levels 1–50. Then Joseph L. Traub collected another 35 levels and included them with XSokoban, his version for Xwindows. These levels, along with a few more from the current XSokoban distribution, form my “Extra” collection.
In 1993, Phil Shapiro <pshapiro@aol.com> made the levels in “Simple Sokoban” for those who found the original levels too difficult. He included the article “Educational Value of Sokoban,” which describes his motivations and why you should be happy if your child spends all his time playing Sokoban.
“Dimitri & Yorick” levels were made by Jacques Duthen <duthen@club-internet.fr>, who also made the Sokoban font. The collection is named after his children. He suggests that the levels are best for kids ages 4–8.
“Still More!” consists of levels by J. Franklin Mentzer <wryter@aol.com>.
I used to include levels from two commercial sokoban version, but removed them in version 2.4.2 after it was pointed out to me that those levels are available commercially on the Macintosh. Unfortunately, these levels are only available with some Japanese sokoban program and I don’t know of a way to obtain them outside Japan. I would like to attempt to negotiate with the copyright owners, but I don’t speak Japanese and don’t know how to contact them.
Radio Shack made a game called “IQ Carrier,” which is a handheld sokoban game with 28 levels. A fan of both games sent me the levels from IQ Carrier and recommended the game for those who would like a nice portable version of sokoban. Those levels were first included in version 2.0 and removed in version 2.4.2 (see previous paragraph).
“Boxxle” is a game for the Nintendo Gameboy. The Gameboy version has two volumes containing about 230 levels. However, all but the 165 I’ve included are duplicates of original levels or IQ Carrier levels. Many thanks are due to John Polhemus <fretsawyer@worldnet.att.net> for typing in all 230 levels and finding almost all of the duplicated levels. The Boxxle levels have been removed in version 2.4.2 (see above).
This is my own implementation for the Macintosh. It does not use any source code from other versions, just their levels.
I know of two other Macintosh sokoban implementations: MacSokoban by Ingemar Ragnemalm <ingemar@lysator.liu.se>, and JSokoban by Jason Townsend <JasonTownsend@mail.utexas.edu>.
I don’t plan to port this program to Windows, but a few free Windows versions of the game (by other people) do exist. In my not-so-humble opinion,they’re not nearly as good as this Mac version. The Windows versions can probably be found at your local users’ group or online service, or else visit my Sokoban web page for places to download them.
Hints and strategies [If you have any good ones to share, let me know!]
All of the levels included are solvable. Before I had solved all of them myself, John Polhemus solved all the levels I hadn’t (and in the process found a couple errors I’d made in copying the levels). Part of the fun of the game is accomplishing something difficult yourself, so I rarely give hints. When you get stuck on one of the Original Levels, you might be able to try a simpler version of the level in the Simple Sokoban collection. If a simpler version is available, the “Try Simpler Level” command in the Level menu will take you to it. To return, choose “Original Levels” from the Collections menu.
This address (current as of March, 1999) will probably be good into the next millenium. If all else fails, send mail to me at my parents’ address; it will reach me eventually:
123 Millwood Dr.
Tonawanda, NY 14150.
The latest version of Sokoban will be available through my Sokoban page on the World Wide Web at http://members.aol.com/SokobanMac/ or by FTP from better FTP sites worldwide (especially at info-mac mirrors and mac.archive.umich.edu). I also attempt to e-mail announcements of new versions (not more than one or two a year) to fans who have sent me email.
You can copy my e-mail, US mail, or Web page address from the Edit menu; if you have the free Internet Config extension installed, you will also have the option to send these addresses to your Web browser or e-mail application.
I will mail you the latest version of Sokoban if you send me a disk and envelope with sufficient postage or $3 to cover the cost of a disk, mailer, postage, and the hassle of going to the post office. If you don’t live in the US, please be sure to send enough to cover return postage—I already spend much of my free time on Sokoban, and I don’t want to spend all my money supporting it.
Comments, suggestions, even (gasp!) bugs
These can all be reported to me at the above addresses. If you are the first to report a bug or make a useful suggestion, I’ll publicly thank you in the About box of the next version of Sokoban. I also love to get fan mail about Sokoban.
The best way to contact me is by e-mail. I usually respond within a couple days unless I’m out of town. If you contact me by US mail, please include a SASE or at least a stamp for a faster reply. That way I’ll feel bad if I don’t respond to your letter and I won’t have to go out to buy stamps before I can reply.
About the author
I am currently a software engineer at Parametric Technology developing CAD software (unfortunately not on a Mac). I earned a Ph.D. in mathematics at the University of Wisconsin—Madison in 1997, got married six months later, and then moved to the Boston area to work. I’m interested in computational number theory and other algorithms. Programming has been a hobby of mine since my parents got an Apple ][+ back in 1980 or so. When I got my Mac Plus, I wanted to learn all about it. Eventually (after about 4 years and some minor projects), I decided to implement Sokoban and finally learn about programming with the Macintosh toolbox. And it worked.
For more information, a résumé, and a short autobiography, visit my web pages at <http://members.aol.com/SokobanMac/scott/>.
Sokoban was originally written in Think Pascal 3.0, on a Mac Plus running System 6, then System 7, and now System 7.5. Versions 1.2 and higher were done on a Power Macintosh 7100/66 with Think Pascal 4.0.2 and 4.5d4.
System requirements
Sokoban works best under System 7 or later (including MacOS 8), and runs on every machine capable of running System 7 (including my 12 year old Mac Plus!). Sokoban takes up so little memory that it should work under System 7 on a machine with as little as 2 megabyes of RAM. It also works under System 6.0.7, but hasn’t been extensively tested with such old system software.
Version history
2.4.2a (April 10, 1999)
– Fixed a bug in saving and loading scores.
2.4.2 (March 19, 1999)
– Fixed a bug that prevented some sounds from being usable.
– Removed Boxxle and IQ Carrier levels because they might be infringing on a Japanese copyright.
2.4.1 (November 12, 1998)
– Updated my address and included some more levels.
2.4 (March 6, 1998)
– Space bar to redo (and shift-space to undo, option-space to redo a push)
– Solved levels in external collections are remembered
– Modified undo to undo whole actions; now a drag-and-drop move is undone with a single push of the ESC key
– Updated my addresses
– Sound support added
– More-visible crosshair cursor
2.3 (Jan 15, 1997)
– Drag level out to edit, drag in to play (shift-drag a whole collection out)
– Includes Sokoban font for easier level making
– Added some levels for kids ages 4–8
– Brief help available within program
– Automatically saves and restores your work when you quit
– Copy my addresses from the program
– More resistant to score file corruption in case of a crash
– The hand cursor can be disabled with cmd-shift-H (for children, perhaps)
– Works with System 6 again
2.2 (April 30, 1996)
– Fixed Boxxle level #81 and Simple Sokoban level #16—I’d messed them up accidentally.
– Added drag and drop movement
– New Copland-style graphics
– Saves and loads best solutions and displays your best score for a level.
– Level commands expelled from File menu; they start their own Level menu
– Added ability to copy or paste a sequence of moves to or from the game.
– Gratuitous 3D rendered graphic triples size of documentation file
2.1 (February 24, 1996)
– Added levels from Boxxle game
– Added three more (hidden) title screens (from John Polhemus)
– Able to select your own keys for keyboard play
– Allows 18-row levels (up one from 17)
– Text collections may have 100 levels
– Fixed two minor cosmetic bugs
– Corrected IQ Carrier level 5 (oops! the mistake made it unsolvable)
– Can now drag diagonally with the mouse
2.0 (February 2, 1996)
– 10000 undos possible (and they require less memory than the 500 undos did in version 1.2)
– After restarting, you can Redo to replay the moves you made the first time around.
– System 7 only (but now system 7 savvy: it handles the basic 4 apple events).
– Completely reorganized the code.
– Level Collections! Now the old levels 51-85 are part of the “Extra” collection.
– More levels; changed Extra levels 51-53 to be harder (they were way too easy).
– Multiple levels in a text file.
– Scores file created in same folder as Sokoban, if possible.
– Can begin by double-clicking a score file.
– Looks better on 256-color monitors. (thanks to Scott Armitage)
– Lets you admire a finished level before continuing to the next one.
– Much cooler about box
– Balloon help for the menus
– Actually requires less memory than version 1.2!
1.2 (Oct. 3, 1994): Fixed the wall on level 13 and added diagonal key support (inspired by a beta copy of Jason Townsend’s JSokoban).
1.1.1 (Sept. 8, 1993): Fixed a bug that made the display all black on machines with monochrome monitors, color QuickDraw, and system 6 or lower.
1.1 (April 27, 1993): Thanks to Russell Owen for all his suggestions and icons.
– Better looking walls and graphics.
– Bigger undo buffer (now you can undo 500 moves)
– New movement options: click to move to a square, option-arrow to select a square to move to, drag with the mouse to move the player.
– Faster shortest path algorithm (the old one was brain dead).
– Supports drag-and-drop of screen files (text files).
